fix: types & config fixes by sujalgoel · Pull Request #40 · webpack/webpack-doc-kit

sujalgoel · 2026-03-22T20:52:03Z

Summary

Fixes #30

The custom type resolver in plugins/theme/partials/types.mjs was collapsing TypeScript types too aggressively, producing semantically inaccurate documentation output. This PR restores the correct semantics now that @node-core/doc-kit supports generic types.

Changes

reference types now include generic type arguments
- Before: {Map}, {ReadonlySet}, {Record}
- After: {Map<string, number>}, {ReadonlySet<string>}, {Record<string, string|string[]|T>}
tuple types now render as tuple syntax instead of union syntax
- Before: {number|number|number}
- After: {[number, number, number]}
conditional types now preserve the full conditional structure
- Before: {TrueType|FalseType}
- After: {CheckType extends ExtendsType ? TrueType : FalseType}
optional tuple members now render with a trailing ? suffix
indexedAccess types now render as T[K] instead of just T

Verification

After regenerating docs with npm run generate-docs, the affected files show correct output:

pages/v5.x/webpack/namespaces/esm.md: {Map<string, number>}, {ReadonlySet<string>}, {Iterable<Chunk>}
pages/v5.x/webpack/namespaces/sharing.md: {Record<string, string|string[]|T>}
pages/v5.x/webpack/namespaces/dependencies.md: {[number, number]} instead of {number|number}

The regenerated pages/v5.x/ output is included in this PR.

linux-foundation-easycla · 2026-03-22T20:52:14Z

The committers listed above are authorized under a signed CLA.

✅ login: avivkeller / name: Aviv Keller (3b33ac8)
✅ login: sujalgoel / name: Sujal Goel (3b33ac8)

avivkeller · 2026-03-22T21:12:15Z

doc-kit supports generics, but only basic ones at the moment. Most of these are yes to be supported. You'll need to use syntax like Tuple<,,>, etc

avivkeller · 2026-03-22T21:13:03Z

plugins/theme/partials/types.mjs

+      return resolve(type.elementType) + '?';
+


When a type is optional, we should just return the type, there's other ways to say it's optional in doc-kit

Done, reverted to just returning the type.

avivkeller · 2026-03-22T21:13:16Z

plugins/theme/partials/types.mjs

-      return union(type.elements);
+      return `[${(type.elements ?? []).map(resolve).join(', ')}]`;


Tuple<...>

Updated to Tuple<>.

avivkeller · 2026-03-22T21:13:59Z

plugins/theme/partials/types.mjs

    case 'conditional':
-      return `${resolve(type.trueType)}|${resolve(type.falseType)}`;
+      return `${resolve(type.checkType)} extends ${resolve(type.extendsType)} ? ${resolve(type.trueType)} : ${resolve(type.falseType)}`;


We don't support this yet, please revert

avivkeller · 2026-03-22T21:14:14Z

plugins/theme/partials/types.mjs

+
    case 'indexedAccess':
-      return resolve(type.elementType ?? type.objectType);
+      return `${resolve(type.objectType)}[${resolve(type.indexType)}]`;


We don't support this yet

avivkeller · 2026-03-22T21:39:02Z

Just because generics render a bit strange in the markdown, doesn't mean they'll render strange in doc-kit, please keep the curly brace syntax

sujalgoel · 2026-03-22T22:17:55Z

Updated the tuple case to use Tuple<> format.

sujalgoel · 2026-03-22T22:17:56Z

Reverted to curly brace syntax.

avivkeller

Thank you!

avivkeller · 2026-03-22T22:23:03Z

plugins/theme/partials/types.mjs

+      return resolve(type.elementType);
+


Suggested change

return resolve(type.elementType);

Done, merged with indexedAccess.

avivkeller · 2026-03-22T22:23:45Z

plugins/theme/partials/types.mjs

-    case 'reference':
      return type.name;

+    case 'reference': {


We can merge this with the above case

Done, merged intrinsic and reference into one case.

avivkeller · 2026-03-22T22:24:23Z

plugins/theme/partials/types.mjs


    case 'tuple':
-      return union(type.elements);
+      return `Tuple<${(type.elements ?? []).map(resolve).join(', ')}>`;


nit: let's make union(type.elements, ', ') work

Done, updated union to accept a separator param and used union(type.elements, ', ') for tuple.

avivkeller · 2026-03-22T22:26:11Z

I'll regenerate the docs to make the check pass when I get a chance

sujalgoel · 2026-03-22T22:28:07Z

Thanks!

Co-Authored-By: Aviv Keller <me@aviv.sh>

sujalgoel force-pushed the fix/type-renderer-preserve-generics branch from 82d256e to db8f98f Compare March 22, 2026 21:06

avivkeller requested changes Mar 22, 2026

View reviewed changes

sujalgoel force-pushed the fix/type-renderer-preserve-generics branch 2 times, most recently from d6f52e0 to 36c52b8 Compare March 22, 2026 22:17

avivkeller approved these changes Mar 22, 2026

View reviewed changes

sujalgoel force-pushed the fix/type-renderer-preserve-generics branch from 36c52b8 to 3c80ad6 Compare March 22, 2026 22:27

fix: types & config fixes

3b33ac8

Co-Authored-By: Aviv Keller <me@aviv.sh>

avivkeller force-pushed the fix/type-renderer-preserve-generics branch from 3c80ad6 to 3b33ac8 Compare March 23, 2026 14:18

avivkeller changed the title ~~fix(types): preserve TypeScript semantics in type renderer~~ fix: types & config fixes Mar 23, 2026

avivkeller merged commit 348f7d0 into webpack:main Mar 23, 2026
3 checks passed

		return union(type.elements);
		return `[${(type.elements ?? []).map(resolve).join(', ')}]`;

Conversation

sujalgoel commented Mar 22, 2026

Summary

Changes

Verification

Uh oh!

linux-foundation-easycla bot commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

avivkeller commented Mar 22, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Mar 22, 2026

Uh oh!

sujalgoel commented Mar 22, 2026

Uh oh!

sujalgoel commented Mar 22, 2026

Uh oh!

avivkeller left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avivkeller commented Mar 22, 2026

Uh oh!

sujalgoel commented Mar 22, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

linux-foundation-easycla bot commented Mar 22, 2026 •

edited

Loading